package cmpe273.proj1.dao;

import java.util.List;

import cmpe273.proj1.model.Course;

/**
 * This interface represents a contract for a DAO for the {@link Course} model.
 * Note that all methods which returns the {@link Course} from the DB, will not
 * fill the model with the password, due to security reasons.
 *
 * @author BalusC
 * @link http://balusc.blogspot.com/2008/07/dao-tutorial-data-layer.html
 */
public interface CourseDAO {

    // Actions ------------------------------------------------------------------------------------

    /**
     * Returns the Course from the database matching the given ID, otherwise null.
     * @param id The ID of the Course to be returned.
     * @return The Course from the database matching the given ID, otherwise null.
     * @throws DAOException If something fails at database level.
     */
    public Course find(Long id) throws DAOException;

    /**
     * Returns the Course from the database matching the given name and section, otherwise null.
     * @param name The name of the Course to be returned.
     * @param section The section of the Course to be returned.
     * @return The Course from the database matching the given name and section, otherwise null.
     * @throws DAOException If something fails at database level.
     */
    public Course find(String name, String section) throws DAOException;

    /**
     * Returns a list of all Courses from the database ordered by Course ID. The list is never null and
     * is empty when the database does not contain any Course.
     * @return A list of all Courses from the database ordered by Course ID.
     * @throws DAOException If something fails at database level.
     */
    public List<Course> list() throws DAOException;
    
    /**
     * Returns a list of all Courses from the database ordered by Course ID that match non-null parameters.
     * The list is never null and is empty when the database does not contain any Course.
     * @param searchParams A Course object where those parameters to search by are not-null.
     * Search for strings is "LIKE '%param%'" (i.e. contains), search for integers is exact
     * @return A list of all Courses from the database ordered by Course ID that match search parameters.
     * @throws DAOException If something fails at database level.
     */
    public List<Course> search(Course searchParams) throws DAOException;

    /**
     * Create the given Course in the database. The Course ID must be null, otherwise it will throw
     * IllegalArgumentException. After creating, the DAO will set the obtained ID in the given Course.
     * @param c The Course to be created in the database.
     * @throws IllegalArgumentException If the Course ID is not null.
     * @throws DAOException If something fails at database level.
     */
    public void create(Course c) throws IllegalArgumentException, DAOException;

    /**
     * Update the given Course in the database. The Course ID must not be null, otherwise it will throw
     * IllegalArgumentException.
     * @param c The Course to be updated in the database.
     * @throws IllegalArgumentException If the Course ID is null.
     * @throws DAOException If something fails at database level.
     */
    public void update(Course c) throws IllegalArgumentException, DAOException;

    /**
     * Delete the given Course from the database. After deleting, the DAO will set the ID of the given
     * Course to null.
     * @param c The Course to be deleted from the database.
     * @throws DAOException If something fails at database level.
     */
    public void delete(Course c) throws DAOException;
}